<html>
<head>
<meta http-equiv="Content-Type" content="text/html; charset=UTF-8">
<title>SafeNumeric&lt;T&gt;</title>
<link rel="stylesheet" href="boostbook.css" type="text/css">
<meta name="generator" content="DocBook XSL Stylesheets V1.79.1">
<link rel="home" href="index.html" title="Safe Numerics">
<link rel="up" href="concepts.html" title="Type Requirements">
<link rel="prev" href="integer.html" title="Integer&lt;T&gt;">
<link rel="next" href="promotion_policy.html" title="PromotionPolicy&lt;PP&gt;">
</head>
<body bgcolor="white" text="black" link="#0000FF" vlink="#840084" alink="#0000FF">
<table cellpadding="2" width="100%"><tr>
<td valign="top"><img href="index.html" height="164px" src="pre-boost.jpg" alt="Library Documentation Index"></td>
<td><h2>Safe Numerics</h2></td>
</tr></table>
<div class="spirit-nav">
<a accesskey="p" href="integer.html"><img src="images/prev.png" alt="Prev"></a><a accesskey="u" href="concepts.html"><img src="images/up.png" alt="Up"></a><a accesskey="h" href="index.html"><img src="images/home.png" alt="Home"></a><a accesskey="n" href="promotion_policy.html"><img src="images/next.png" alt="Next"></a>
</div>
<div class="section">
<div class="titlepage"><div><div><h3 class="title">
<a name="safe_numerics.safe_numeric_concept"></a>SafeNumeric&lt;T&gt;</h3></div></div></div>
<div class="toc"><dl class="toc">
<dt><span class="section"><a href="safe_numeric_concept.html#idm488720563920">Description</a></span></dt>
<dt><span class="section"><a href="safe_numeric_concept.html#idm488720562464">Refinement of</a></span></dt>
<dt><span class="section"><a href="safe_numeric_concept.html#idm488720560112">Notation</a></span></dt>
<dt><span class="section"><a href="safe_numeric_concept.html#idm488720542640">Associated Types</a></span></dt>
<dt><span class="section"><a href="safe_numeric_concept.html#idm488720533984">Valid Expressions</a></span></dt>
<dt><span class="section"><a href="safe_numeric_concept.html#idm488720454272">Invariants</a></span></dt>
<dt><span class="section"><a href="safe_numeric_concept.html#idm488720452672">Models</a></span></dt>
<dt><span class="section"><a href="safe_numeric_concept.html#idm488720448336">Header</a></span></dt>
</dl></div>
<div class="section">
<div class="titlepage"><div><div><h4 class="title">
<a name="idm488720563920"></a>Description</h4></div></div></div>
<p>This holds an arithmetic value which can be used as a replacement
    for built-in C++ arithmetic values. These types differ from their built-in
    counter parts in that the are guaranteed not to produce invalid arithmetic
    results. These operations return safe types rather than built-in
    types.</p>
</div>
<div class="section">
<div class="titlepage"><div><div><h4 class="title">
<a name="idm488720562464"></a>Refinement of</h4></div></div></div>
<p><a class="link" href="numeric.html" title="Numeric&lt;T&gt;">Numeric</a> or <a class="link" href="integer.html" title="Integer&lt;T&gt;">Integer</a></p>
</div>
<div class="section">
<div class="titlepage"><div><div><h4 class="title">
<a name="idm488720560112"></a>Notation</h4></div></div></div>
<div class="informaltable"><table class="table">
<colgroup>
<col align="left">
<col align="left">
</colgroup>
<thead><tr>
<th align="left">Symbol</th>
<th align="left">Description</th>
</tr></thead>
<tbody>
<tr>
<td align="left"><code class="computeroutput">T, U</code></td>
<td align="left">Types fulfilling <a class="link" href="numeric.html" title="Numeric&lt;T&gt;">Numeric</a> or <a class="link" href="integer.html" title="Integer&lt;T&gt;">Integer</a> type
            requirements.</td>
</tr>
<tr>
<td align="left">t, u</td>
<td align="left">objects of types T, U</td>
</tr>
<tr>
<td align="left">S</td>
<td align="left">A type fulfilling SafeNumeric type requirements</td>
</tr>
<tr>
<td align="left">s, s1, s2</td>
<td align="left">objects of types S</td>
</tr>
<tr>
<td align="left">op</td>
<td align="left">C++ infix operator supported by underlying type T</td>
</tr>
<tr>
<td align="left">prefix_op</td>
<td align="left">C++ prefix operator: -, +, ~, ++, -- supported by
            underlying type T</td>
</tr>
<tr>
<td align="left">postfix_op</td>
<td align="left">C++ postfix operator:++, -- supported by underlying type
            T</td>
</tr>
<tr>
<td align="left">assign_op</td>
<td align="left">C++ assignment operator</td>
</tr>
</tbody>
</table></div>
</div>
<div class="section">
<div class="titlepage"><div><div><h4 class="title">
<a name="idm488720542640"></a>Associated Types</h4></div></div></div>
<div class="informaltable"><table class="table">
<colgroup>
<col align="left">
<col align="left">
</colgroup>
<tbody>
<tr>
<td align="left"><a class="link" href="promotion_policy.html" title="PromotionPolicy&lt;PP&gt;"><code class="computeroutput">PromotionPolicy</code></a></td>
<td align="left">In C++ expressions, arguments must be of the same type. If
            they are not, all arguments are converted to a common type in
            accordance with rules of the C++ standard. For some applications
            of the safe numerics library, we might want conversions which are
            different than the standard ones. This class type implements the
            conversion functions that are to be used with the safe numeric
            type being instantiated.</td>
</tr>
<tr>
<td align="left"><a class="link" href="exception_policy.html" title="ExceptionPolicy&lt;EP&gt;"><code class="computeroutput">ExceptionPolicy</code></a></td>
<td align="left">The exception policy specifies what is to occur when a safe
            operation cannot return a valid result. A type is an
            ExceptionPolicy if it has specific functions for handling
            exceptional events that occur in the course of safe numeric
            operations.</td>
</tr>
</tbody>
</table></div>
</div>
<div class="section">
<div class="titlepage"><div><div><h4 class="title">
<a name="idm488720533984"></a>Valid Expressions</h4></div></div></div>
<div class="informaltable"><table class="table">
<colgroup>
<col align="left">
<col align="left">
<col align="left">
</colgroup>
<thead><tr>
<th align="left">Expression</th>
<th align="left">Result Type</th>
<th align="left">Description</th>
</tr></thead>
<tbody>
<tr>
<td align="left"><code class="computeroutput">s op t</code></td>
<td align="left">unspecified S</td>
<td align="left"><p>invoke C++ operator op and return another
              SafeNumeric type.</p></td>
</tr>
<tr>
<td align="left"><code class="computeroutput">t op s</code></td>
<td align="left">unspecified S</td>
<td align="left"><p>invoke C++ operator op and return another
              SafeNumeric type.</p></td>
</tr>
<tr>
<td align="left"><code class="computeroutput">s1 op s2</code></td>
<td align="left">unspecified S</td>
<td align="left"><p>invoke C++ operator op and return another
              SafeNumeric type.</p></td>
</tr>
<tr>
<td align="left"><code class="computeroutput">prefix_op S</code></td>
<td align="left">unspecified S</td>
<td align="left"><p>invoke C++ operator <code class="computeroutput">prefix_op</code> and
              return another SafeNumeric type.</p></td>
</tr>
<tr>
<td align="left"><code class="computeroutput">S postfix_op</code></td>
<td align="left">unspecified S</td>
<td align="left"><p>invoke C++ operator <code class="computeroutput">postfix_op</code> and
              return another SafeNumeric type.</p></td>
</tr>
<tr>
<td align="left"><code class="computeroutput">s assign_op t</code></td>
<td align="left">S &amp;</td>
<td align="left"><p>convert t to type S and assign it to s.
              </p></td>
</tr>
<tr>
<td align="left"><code class="computeroutput">t assign_op s</code></td>
<td align="left">T &amp;</td>
<td align="left"><p>convert s to type T and assign it to s. If the
              value t cannot be represented as an instance of type S, it is an
              error.</p></td>
</tr>
<tr>
<td align="left"><code class="computeroutput">S(t)</code></td>
<td align="left">S</td>
<td align="left"><p>construct an instance of S from a value of type T.
              In this case, T is referred to as the base type of S. If the
              value t cannot be represented as an instance of type S, it is an
              exception condition is invoked. </p></td>
</tr>
<tr>
<td align="left"><code class="computeroutput">S</code></td>
<td align="left">S</td>
<td align="left"><p>construct an uninitialized instance of
              S.</p></td>
</tr>
<tr>
<td align="left"><code class="computeroutput">T(s)</code></td>
<td align="left">T</td>
<td align="left"><p>implicit conversion of the value of s to type T. If
              the value of s cannot be correctly represented as a type T, an
              exception condition is invoked.</p></td>
</tr>
<tr>
<td align="left"><code class="computeroutput">static_cast&lt;T&gt;(s)</code></td>
<td align="left">T</td>
<td align="left"><p>convert the value of s to type T. If the value of s
              cannot be correctly represented as a type T, an exception
              condition is invoked. </p></td>
</tr>
<tr>
<td align="left"><code class="computeroutput">is_safe&lt;S&gt;</code></td>
<td align="left"><code class="computeroutput">std::true_type</code></td>
<td align="left"><p>type trait to query whether any type S fulfills the
              requirements for a SafeNumeric type.</p></td>
</tr>
<tr>
<td align="left"><code class="computeroutput">get_promotion_policy&lt;S&gt;</code></td>
<td align="left">S</td>
<td align="left"><p>Retrieve the <a class="link" href="promotion_policy.html" title="PromotionPolicy&lt;PP&gt;"><code class="computeroutput">PromotionPolicy</code></a><code class="computeroutput">
              which is used by the specified safe type</code>.</p></td>
</tr>
<tr>
<td align="left"><code class="computeroutput">get_exception_policy&lt;S&gt;</code></td>
<td align="left">S</td>
<td align="left"><p>Retrieve the <a class="link" href="exception_policy.html" title="ExceptionPolicy&lt;EP&gt;"><code class="computeroutput">ExceptionPolicy</code></a>
              which is used by the specified safe type.</p></td>
</tr>
<tr>
<td align="left"><code class="computeroutput">base_type&lt;S&gt;::type</code></td>
<td align="left">T</td>
<td align="left"><p>Retrieve the base type of a given safe
              type.</p></td>
</tr>
<tr>
<td align="left"><code class="computeroutput">base_value(s)</code></td>
<td align="left">T</td>
<td align="left"><p>Retrieve the value of an instance of a safe type.
              This is equivalent to
              <code class="computeroutput">static_cast&lt;base_type&lt;S&gt;&gt;(s)</code>.</p></td>
</tr>
</tbody>
</table></div>
<div class="itemizedlist"><ul class="itemizedlist" style="list-style-type: disc; ">
<li class="listitem"><p>The result of any binary operation where one or both of the
        operands is a SafeNumeric type is also a SafeNumeric type. The
        specific type is determined by the promotion rules implement in the
        PromotionPolicy returned by get_promotion_policy&lt;S&gt; where S is
        the result type.</p></li>
<li class="listitem"><p>All the expressions in the above table are
        <code class="computeroutput">constexpr</code> expressions.</p></li>
<li class="listitem"><p>Binary expressions which are not assignments and whose operands
        are both safe types require that promotion and exception policies of
        the operands be identical.</p></li>
<li class="listitem"><p><code class="computeroutput">Operations on safe types are supported if and only if the
        same operation is supported on the underlying types. For example, the
        binary operations |</code>, <code class="computeroutput">&amp;</code>, <code class="computeroutput">^</code> and
        <code class="computeroutput">~</code> operations defined for safe unsigned integer types. But
        they are not defined for floating point types. Currently the are also
        defined for signed integer types. It's not clear that this is the
        correct decision. On one hand, usage of these operators on signed
        types is almost certainly an error in program logic. But trapping this
        as an error conflicts with the goal of making safe types "drop-in"
        replacements for the corresponding built-in types. In light of this,
        these operators are currently supported as they are for normal
        built-in types.</p></li>
<li class="listitem">
<p>Safe Numeric types will be implicitly converted to built-in
        types when appropriate. Here's an example:</p>
<pre class="programlisting"><span class="keyword">void</span> <span class="identifier">f</span><span class="special">(</span><span class="keyword">int</span><span class="special">)</span><span class="special">;</span>

<span class="keyword">int</span> <span class="identifier">main</span><span class="special">(</span><span class="special">)</span><span class="special">{</span>
    <span class="keyword">long</span> <span class="identifier">x</span><span class="special">;</span>
    <span class="identifier">f</span><span class="special">(</span><span class="identifier">x</span><span class="special">)</span><span class="special">;</span>         <span class="comment">// OK - builtin implicit version</span>
    <span class="identifier">safe</span><span class="special">&lt;</span><span class="keyword">long</span><span class="special">&gt;</span> <span class="identifier">y</span><span class="special">;</span>
    <span class="identifier">f</span><span class="special">(</span><span class="identifier">y</span><span class="special">)</span><span class="special">;</span>
    <span class="keyword">return</span> <span class="number">0</span><span class="special">;</span>
<span class="special">}</span></pre>
<p>This behavior supports the concept of
        <code class="computeroutput">safe&lt;T&gt;</code> as being a "drop-in" replacement for a
        <code class="computeroutput">T</code>.</p>
</li>
</ul></div>
</div>
<div class="section">
<div class="titlepage"><div><div><h4 class="title">
<a name="idm488720454272"></a>Invariants</h4></div></div></div>
<p>The fundamental requirement of a SafeNumeric type is that it
    implements all C++ operations permitted on its base type in a way the
    prevents the return of an incorrect arithmetic result. Various
    implementations of this concept may handle circumstances which produce
    such results differently (throw exception, compile time trap, etc..). But
    no implementation should return an arithmetically incorrect result.</p>
</div>
<div class="section">
<div class="titlepage"><div><div><h4 class="title">
<a name="idm488720452672"></a>Models</h4></div></div></div>
<p><code class="computeroutput">safe&lt;T&gt;</code></p>
<p><code class="computeroutput">safe_signed_range&lt;-11, 11&gt;</code></p>
<p><code class="computeroutput">safe_unsigned_range&lt;0, 11&gt;</code></p>
<p><code class="computeroutput">safe_signed_literal&lt;4&gt;</code></p>
</div>
<div class="section">
<div class="titlepage"><div><div><h4 class="title">
<a name="idm488720448336"></a>Header</h4></div></div></div>
<p><a href="../../include/boost/safe_numerics/concept/safe_numeric.hpp" target="_top"><code class="computeroutput">#include
    &lt;boost/safe_numerics/concepts/safe_numeric.hpp&gt;</code></a></p>
</div>
</div>
<table xmlns:rev="http://www.cs.rpi.edu/~gregod/boost/tools/doc/revision" width="100%"><tr>
<td align="left"></td>
<td align="right"><div class="copyright-footer">Copyright © 2012-2018 Robert Ramey<p><a href="http://www.boost.org/LICENSE_1_0.txt" target="_top">Subject to Boost
      Software License</a></p>
</div></td>
</tr></table>
<hr>
<div class="spirit-nav">
<a accesskey="p" href="integer.html"><img src="images/prev.png" alt="Prev"></a><a accesskey="u" href="concepts.html"><img src="images/up.png" alt="Up"></a><a accesskey="h" href="index.html"><img src="images/home.png" alt="Home"></a><a accesskey="n" href="promotion_policy.html"><img src="images/next.png" alt="Next"></a>
</div>
</body>
</html>
